home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1994 February: Tool Chest / Dev.CD Feb 94.toast / New System Software Extensions / QuickDraw™ GX v1.0ß2 / Interfaces & Libraries / interfaces / Collections.h < prev    next >
Encoding:
C/C++ Source or Header  |  1993-07-29  |  10.9 KB  |  422 lines  |  [TEXT/MPS ]
  1. /* ------------------------------------------------------------------------------
  2.  
  3.     FILENAME
  4.         Collections.h
  5.  
  6.     DESCRIPTION
  7.         This file contains all of the public data structures, constants, and 
  8.         function declarations for the Collection Manager.
  9.  
  10.     COPYRIGHT
  11.         Copyright © Apple Computer, Inc. 1989, 1990, 1991, 1992, 1993
  12.         All rights reserved. 
  13.  
  14. ------------------------------------------------------------------------------- */
  15.  
  16.  
  17. #ifndef __COLLECTIONMANAGER__
  18. #define __COLLECTIONMANAGER__
  19.  
  20. #ifndef __TYPES__
  21. #include <Types.h>
  22. #endif
  23.  
  24.  
  25. /*************/
  26. /* Constants */
  27. /*************/
  28.  
  29.  
  30. /* Collection Manager Gestalt Selector... */
  31.  
  32. enum {
  33.     gestaltCollectionMgrVersion = 'cltn'
  34. };
  35.  
  36.  
  37. /* Collection Manager Error Result Codes... */
  38.  
  39. enum {
  40.     collectionItemLockedErr = -5750,
  41.     collectionItemNotFoundErr = -5751,
  42.     collectionIndexRangeErr = -5752,
  43.     collectionVersionErr = -5753
  44. };
  45.  
  46.  
  47. /* Convenience constants for functions which optionally return values... */
  48.  
  49. enum {
  50.     dontWantTag                = 0L,
  51.     dontWantId                = 0L,
  52.     dontWantSize            = 0L,
  53.     dontWantAttributes    = 0L,
  54.     dontWantIndex            = 0L,
  55.     dontWantData            = 0L
  56. };
  57.  
  58.  
  59. /* attributes bits */
  60.  
  61.  
  62. enum {
  63.     noCollectionAttributes = 0x00000000,        /* no attributes bits set */
  64.     allCollectionAttributes = 0xFFFFFFFF,        /* all attributes bits set */
  65.     userCollectionAttributes = 0x0000FFFF,        /* user attributes bits */
  66.     defaultCollectionAttributes = 0x40000000    /* default attributes - unlocked, persistent */
  67. };
  68.  
  69.  
  70. /* 
  71.     Attribute bits 0 through 15 (entire low word) are reserved for use by the application.
  72.     Attribute bits 16 through 31 (entire high word) are reserved for use by the Collection Manager.
  73.     Only bits 31 (collectionLockBit) and 30 (collectionPersistenceBit) currently have meaning.
  74. */
  75.  
  76.  
  77. enum {
  78.     collectionUser0Bit            = 0,
  79.     collectionUser1Bit            = 1,
  80.     collectionUser2Bit            = 2,
  81.     collectionUser3Bit            = 3,
  82.     collectionUser4Bit            = 4,
  83.     collectionUser5Bit            = 5,
  84.     collectionUser6Bit            = 6,
  85.     collectionUser7Bit            = 7,
  86.     collectionUser8Bit            = 8,
  87.     collectionUser9Bit            = 9,
  88.     collectionUser10Bit            = 10,
  89.     collectionUser11Bit            = 11,
  90.     collectionUser12Bit            = 12,
  91.     collectionUser13Bit            = 13,
  92.     collectionUser14Bit            = 14,
  93.     collectionUser15Bit            = 15,
  94.     
  95.     collectionReserved0Bit        = 16,
  96.     collectionReserved1Bit        = 17,
  97.     collectionReserved2Bit        = 18,
  98.     collectionReserved3Bit        = 19,
  99.     collectionReserved4Bit        = 20,
  100.     collectionReserved5Bit        = 21,
  101.     collectionReserved6Bit        = 22,
  102.     collectionReserved7Bit        = 23,
  103.     collectionReserved8Bit        = 24,
  104.     collectionReserved9Bit        = 25,
  105.     collectionReserved10Bit        = 26,
  106.     collectionReserved11Bit        = 27,
  107.     collectionReserved12Bit        = 28,
  108.     collectionReserved13Bit        = 29,
  109.     
  110.     collectionPersistenceBit    = 30,
  111.     collectionLockBit                = 31
  112. };
  113.         
  114.         
  115. /* attribute masks */
  116.  
  117.  
  118. enum {
  119.     collectionUser0Mask            = 1L << collectionUser0Bit,
  120.     collectionUser1Mask            = 1L << collectionUser1Bit,
  121.     collectionUser2Mask            = 1L << collectionUser2Bit,
  122.     collectionUser3Mask            = 1L << collectionUser3Bit,
  123.     collectionUser4Mask            = 1L << collectionUser4Bit,
  124.     collectionUser5Mask            = 1L << collectionUser5Bit,
  125.     collectionUser6Mask            = 1L << collectionUser6Bit,
  126.     collectionUser7Mask            = 1L << collectionUser7Bit,
  127.     collectionUser8Mask            = 1L << collectionUser8Bit,
  128.     collectionUser9Mask            = 1L << collectionUser9Bit,
  129.     collectionUser10Mask            = 1L << collectionUser10Bit,
  130.     collectionUser11Mask            = 1L << collectionUser11Bit,
  131.     collectionUser12Mask            = 1L << collectionUser12Bit,
  132.     collectionUser13Mask            = 1L << collectionUser13Bit,
  133.     collectionUser14Mask            = 1L << collectionUser14Bit,
  134.     collectionUser15Mask            = 1L << collectionUser15Bit,
  135.  
  136.     collectionReserved0Mask        = 1L << collectionReserved0Bit,
  137.     collectionReserved1Mask        = 1L << collectionReserved1Bit,
  138.     collectionReserved2Mask        = 1L << collectionReserved2Bit,
  139.     collectionReserved3Mask        = 1L << collectionReserved3Bit,
  140.     collectionReserved4Mask        = 1L << collectionReserved4Bit,
  141.     collectionReserved5Mask        = 1L << collectionReserved5Bit,
  142.     collectionReserved6Mask        = 1L << collectionReserved6Bit,
  143.     collectionReserved7Mask        = 1L << collectionReserved7Bit,
  144.     collectionReserved8Mask        = 1L << collectionReserved8Bit,
  145.     collectionReserved9Mask        = 1L << collectionReserved9Bit,
  146.     collectionReserved10Mask    = 1L << collectionReserved10Bit,
  147.     collectionReserved11Mask    = 1L << collectionReserved11Bit,
  148.     collectionReserved12Mask    = 1L << collectionReserved12Bit,
  149.     collectionReserved13Mask    = 1L << collectionReserved13Bit,
  150.  
  151.     collectionPersistenceMask    = 1L << collectionPersistenceBit,
  152.     collectionLockMask            = 1L << collectionLockBit
  153. };
  154.  
  155.  
  156.  
  157. /* the Collection Manager trap */
  158.  
  159.  
  160. #define collectionManagerTrap 0xABF6    /* C++ will choke on an enum in a trap definition */
  161.  
  162.  
  163. /***********/
  164. /* Types   */
  165. /***********/
  166.  
  167.  
  168. typedef struct PrivateCollectionRecord *Collection;        /* abstract data type for a collection */
  169.  
  170. typedef long CollectionTag;                                        /* collection member 4 byte tag */
  171.  
  172. typedef pascal OSErr (*CollectionFlattenProc) (long size, void *data, void *refCon);
  173.  
  174. typedef pascal OSErr (*CollectionExceptionProc) (Collection, OSErr);
  175.  
  176.  
  177. /**********************************************************************
  178.  ***************            Public Interfaces            ***********************
  179.  *********************************************************************/
  180.  
  181.  
  182. #ifdef __cplusplus
  183. extern "C" {
  184. #endif
  185.  
  186.  
  187. pascal Collection NewCollection (void)
  188. = {0x7000,collectionManagerTrap};
  189.  
  190.  
  191. pascal void DisposeCollection (Collection)
  192. = {0x7001,collectionManagerTrap};
  193.  
  194.  
  195. pascal Collection CloneCollection (Collection)
  196. = {0x7002,collectionManagerTrap};
  197.  
  198.  
  199. pascal long CountCollectionOwners (Collection)
  200. = {0x7003,collectionManagerTrap};
  201.  
  202.  
  203. pascal Collection CopyCollection (Collection srcCollection, Collection dstCollection)
  204. = {0x7004,collectionManagerTrap};
  205.  
  206.  
  207. pascal long GetCollectionDefaultAttributes (Collection)
  208. = {0x7005,collectionManagerTrap};
  209.  
  210.  
  211. pascal void SetCollectionDefaultAttributes (Collection,
  212.                                                            long whichAttributes,
  213.                                                             long newAttributes)
  214. = {0x7006,collectionManagerTrap};
  215.  
  216.  
  217. pascal long CountCollectionItems (Collection)
  218. = {0x7007,collectionManagerTrap};
  219.  
  220.  
  221. pascal OSErr AddCollectionItem (Collection,
  222.                                              CollectionTag,
  223.                                           long id,
  224.                                           long itemSize,
  225.                                           void *itemData)
  226. = {0x7008,collectionManagerTrap};
  227.  
  228.  
  229. pascal OSErr GetCollectionItem (Collection,
  230.                                            CollectionTag,
  231.                                           long id,
  232.                                           long *itemSize,
  233.                                           void *itemData)
  234. = {0x7009,collectionManagerTrap};
  235.  
  236.  
  237. pascal OSErr RemoveCollectionItem (Collection, CollectionTag, long id)
  238. = {0x700A,collectionManagerTrap};
  239.  
  240.  
  241. pascal OSErr SetCollectionItemInfo (Collection,
  242.                                                    CollectionTag,
  243.                                                     long id,
  244.                                                     long whichAttributes,
  245.                                                   long newAttributes)
  246. = {0x700B,collectionManagerTrap};
  247.  
  248.  
  249. pascal OSErr GetCollectionItemInfo (Collection,
  250.                                                    CollectionTag,
  251.                                                     long id,
  252.                                                   long *index,
  253.                                                   long *itemSize,
  254.                                                     long *attributes)
  255. = {0x700C,collectionManagerTrap};
  256.  
  257.  
  258. pascal OSErr ReplaceIndexedCollectionItem (Collection,
  259.                                                                long index,
  260.                                                             long itemSize,
  261.                                                            void *itemData)
  262. = {0x700D,collectionManagerTrap};
  263.  
  264.  
  265. pascal OSErr GetIndexedCollectionItem (Collection,
  266.                                                           long index,
  267.                                                       long *itemSize,
  268.                                                      void *itemData)
  269. = {0x700E,collectionManagerTrap};
  270.  
  271.  
  272.  
  273. pascal OSErr RemoveIndexedCollectionItem (Collection, long index)
  274. = {0x700F,collectionManagerTrap};
  275.  
  276.  
  277. pascal OSErr SetIndexedCollectionItemInfo (Collection,
  278.                                                            long index,
  279.                                                           long whichAttributes,
  280.                                                            long newAttributes)
  281. = {0x7010,collectionManagerTrap};
  282.  
  283.  
  284. pascal OSErr GetIndexedCollectionItemInfo (Collection,
  285.                                                                long index,
  286.                                                            CollectionTag *,
  287.                                                         long *id,
  288.                                                          long *itemSize,
  289.                                                         long *attributes)
  290. = {0x7011,collectionManagerTrap};
  291.  
  292.  
  293. pascal Boolean CollectionTagExists (Collection, CollectionTag)
  294. = {0x7012,collectionManagerTrap};
  295.  
  296.  
  297. pascal long CountCollectionTags (Collection)
  298. = {0x7013,collectionManagerTrap};
  299.  
  300.  
  301. pascal OSErr GetIndexedCollectionTag (Collection,
  302.                                                   long whichTag,
  303.                                                   CollectionTag *)
  304. = {0x7014,collectionManagerTrap};
  305.  
  306.  
  307. pascal long CountTaggedCollectionItems (Collection, CollectionTag)
  308. = {0x7015,collectionManagerTrap};
  309.  
  310.  
  311. pascal OSErr GetTaggedCollectionItem (Collection,
  312.                                                   CollectionTag,
  313.                                                    long whichItem,
  314.                                                   long *itemSize,
  315.                                                    void *itemData)
  316. = {0x7016,collectionManagerTrap};
  317.  
  318.  
  319. pascal OSErr GetTaggedCollectionItemInfo (Collection,
  320.                                                            CollectionTag,
  321.                                                           long whichItem,
  322.                                                           long *id,
  323.                                                           long *index,
  324.                                                           long *itemSize,
  325.                                                           long *attributes)
  326. = {0x7017,collectionManagerTrap};
  327.  
  328.  
  329. pascal void PurgeCollection (Collection,
  330.                                       long whichAttributes,
  331.                                       long matchingAttributes)
  332. = {0x7018,collectionManagerTrap};
  333.  
  334.  
  335. pascal void PurgeCollectionTag (Collection, CollectionTag)
  336. = {0x7019,collectionManagerTrap};
  337.  
  338.  
  339. pascal void EmptyCollection (Collection)
  340. = {0x701A,collectionManagerTrap};
  341.  
  342.  
  343. pascal OSErr FlattenCollection (Collection,
  344.                                           CollectionFlattenProc,
  345.                                           void *refCon)
  346. = {0x701B,collectionManagerTrap};
  347.  
  348.  
  349. pascal OSErr FlattenPartialCollection (Collection,
  350.                                                       CollectionFlattenProc,
  351.                                                       void *refCon,
  352.                                                      long whichAttributes,
  353.                                                      long matchingAttributes)
  354. = {0x701C,collectionManagerTrap};
  355.  
  356.  
  357. pascal OSErr UnflattenCollection (Collection,
  358.                                              CollectionFlattenProc,
  359.                                              void *refCon)
  360. = {0x701D,collectionManagerTrap};
  361.  
  362.  
  363. pascal CollectionExceptionProc GetCollectionExceptionProc (Collection)
  364. = {0x701E,collectionManagerTrap};
  365.  
  366.  
  367. pascal void SetCollectionExceptionProc (Collection, CollectionExceptionProc)
  368. = {0x701F,collectionManagerTrap};
  369.  
  370.  
  371.  
  372. /*****************************************************************************************/
  373. /* Utility Routines for handle-based access...                                                          */
  374. /*****************************************************************************************/
  375.  
  376.  
  377.  
  378. pascal Collection GetNewCollection (short collectionID)
  379. = {0x7020,collectionManagerTrap};
  380.  
  381.  
  382. pascal OSErr AddCollectionItemHdl (Collection aCollection,
  383.                                                    CollectionTag tag,
  384.                                                    long id,
  385.                                                    Handle itemData)
  386. = {0x7021,collectionManagerTrap};
  387.  
  388.  
  389. pascal OSErr GetCollectionItemHdl (Collection aCollection,
  390.                                                  CollectionTag tag,
  391.                                                  long id,
  392.                                                    Handle itemData)
  393. = {0x7022,collectionManagerTrap};
  394.  
  395.                           
  396. pascal OSErr ReplaceIndexedCollectionItemHdl (Collection aCollection,
  397.                                                                    long index,
  398.                                                                Handle itemData)
  399. = {0x7023,collectionManagerTrap};
  400.  
  401.                                     
  402. pascal OSErr GetIndexedCollectionItemHdl (Collection aCollection,
  403.                                                              long index,
  404.                                                              Handle itemData)
  405. = {0x7024,collectionManagerTrap};
  406.  
  407.                           
  408. pascal OSErr FlattenCollectionToHdl (Collection aCollection, Handle flattened)
  409. = {0x7025,collectionManagerTrap};
  410.  
  411.  
  412. pascal OSErr UnflattenCollectionFromHdl (Collection aCollection, Handle flattened)
  413. = {0x7026,collectionManagerTrap};
  414.  
  415.  
  416. #ifdef __cplusplus
  417. }
  418. #endif
  419.  
  420.  
  421. #endif
  422.